home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / c / RsrcTrackLib.readme < prev    next >
Encoding:
Text File  |  1998-10-31  |  9.6 KB  |  235 lines
  1. Short:    Shared Library to do ressource tracking
  2. Author:   BURNAND Patrick pburnand@yahoo.com
  3. Uploader: pburnand@yahoo.com
  4. Type:     dev/c
  5.  
  6.  
  7.  
  8. GOALS OF THIS LIBRARY
  9. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  10.  
  11.    One of the major problem when you are developping software for the Amiga is
  12.    the lack of some kind of automation to manage ressources.  The programmer
  13.    must do all the work «manually» and even the smallest error could lead to a
  14.    system crash.  (In some error condition, you can easily free a memory-block
  15.    twice...)
  16.  
  17.    This project is an attempt to implement ressource tracking on the Amiga.
  18.  
  19.  
  20.  
  21. FEATURES OF THE PACKAGE
  22. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  23.  
  24.    Fast:
  25.       A stack of ressource tracking records is allocated only once.  So
  26.       creating a new record is basically only some pointer manipulations...
  27.       See the simple benchmarks below.  It was one of my main goal not to slow
  28.       down the Amiga too much...
  29.  
  30.    Programs becomes shorter:
  31.       Because there is no need to free the ressources and the management of
  32.       allocations fails becomes really simpler.
  33.  
  34.    Easy to use:
  35.       You only need to call one function to create the ressource tracking
  36.       stack, and then another one to free all ressources and to delete the
  37.       stack.
  38.       The system calls remain exactly the sames.  Only the name is different:
  39.       AllocMem becomes rt_AllocMem and has the same parameters.
  40.  
  41.    Suitable even for small projects:
  42.       This isen't implemented as a link library like others ressource tracking
  43.       systems you can find on Aminet.  This is a small (4kb) shared library.
  44.  
  45.    Totally automatic ressource liberation:
  46.       At the end of your program you only need to call one function to free all
  47.       the ressources that are still allocated.
  48.  
  49.    Custom liberation functions:
  50.       You can tell the library to call functions of your program when it's time
  51.       to deallocate ressources.  This is very similar to ansi c atexit()
  52.       function.  (It seems to only work with the c language)
  53.  
  54.    Secure:
  55.       If the allocation fails, the ressource won't be deallocated.
  56.       You can call the functions to allocate and deallocate the ressource
  57.       tracking stack several times. This can greatly simplify the termination
  58.       of your program.
  59.  
  60.    Easier shared library management:
  61.       To do the allocation and deallocation you only use RessourceTrackingBase.
  62.       And if you want to short-circuit the ressource tracking mechanism, you
  63.       can find the DosBase, IntuitionBase, ... in RessourceTrackingBase.
  64.  
  65.    Not only for c programmers:
  66.       As this is a standard shared library, you have the standard FD file.  So
  67.       it's very easy to adapt the package to every programming language.
  68.  
  69.  
  70.  
  71. LIMITATIONS OF THE PACKAGE
  72. ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  73.  
  74.    As this package is not terminated at all, only a few exec function are
  75.    traced.  But there should be no bug.
  76.  
  77.    If you are interested in expanding this package simply get in touch with me.
  78.    Most of the work is already done and the remaining is very symetric.
  79.  
  80.  
  81.  
  82. BENCHMARKS
  83. ¯¯¯¯¯¯¯¯¯¯
  84.  
  85.    I've done simple benchmarks to see how much the ressource tracking system
  86.    slows down the computer.
  87.  
  88.    It consists of an huge number of memory allocation and liberation and a huge
  89.    number of library opens and closes.  I always have run the benchmark 5 times
  90.    and I took the minimal time.
  91.  
  92.  Test conditions:
  93.  ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  94.    Amiga 1200, Blizzard 1230/IV, 50 MHz, AmigaOS 3.1.
  95.    Test code and library compiled with vbcc 0.6 with all optimisations on.
  96.  
  97.  
  98.  BenchMark 1:  Memory allocation tests:
  99.  ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  100.  
  101.   Test code:
  102.   ¯¯¯¯¯¯¯¯¯¯
  103.    /*  Code used to measure the time needed to allocate memory WITHOUT the
  104.    **  ressourcetracking.library.  It means 409600 memory allocations and
  105.    **  liberations.  */
  106.  
  107.    int i, j;
  108.    APTR mem[4096];
  109.  
  110.    for (i=0;i<100;i++) {               /* do 100 times: */
  111.       for (j=0;j<4096;j++)
  112.          mem[j]=AllocMem(16,MEMF_ANY);   /* do 4096 allocations of 16 bytes */
  113.       for (j=4095;j>=0;j--)
  114.          if (mem[j])                     /* do 4096 pointer tests and */
  115.             FreeMem(mem[j],16);          /* 4096 liberations */
  116.    }
  117.  
  118.    /*  Code used to measure the time needed to allocate memory WITH the
  119.    **  ressourcetracking.library.  It means 409600 memory allocations and
  120.    **  liberations.  */
  121.  
  122.    int i, j;
  123.    APTR mem[4096];
  124.  
  125.    for (i=0;i<100;i++) {               /* do 100 times: */
  126.       for (j=0;j<4096;j++)
  127.          mem[j]=rt_AllocMem(16,MEMF_ANY); /* do 4096 allocations of 16 bytes */
  128.       rt_UnsetMarker();                   /* free all the memory blocks */
  129.    }
  130.  
  131.  
  132.   Results:
  133.   ¯¯¯¯¯¯¯¯
  134.    +-------------------------------------------------------------------------+
  135.    |                             MEASURED TIMES                              |
  136.    +------------------------------------+------------------------------------+
  137.    |  WITH  MemPools 1.22, a patch to   |                                    |
  138.    |    optimize memory allocations     |          WITHOUT MemPools          |
  139.    |        (found on Aminet)           |                                    |
  140.    +----------------+-------------------+----------------+-------------------+
  141.    |  WITH library  |  WITHOUT library  |  WITH library  |  WITHOUT library  |
  142.    +----------------+-------------------+----------------+-------------------+
  143.    |  00:00:28.72   |    00:00:19.08    |  00:01:59.59   |    00:01:29.41    |
  144.    +----------------+-------------------+----------------+-------------------+
  145.  
  146.    +-------------------------------------------------------------------------+
  147.    |                            LIBRARY OVERHEAD                             |
  148.    +------------------------------------+------------------------------------+
  149.    |        WITH  MemPools 1.22         |          WITHOUT MemPools          |
  150.    +------------------------------------+------------------------------------+
  151.    |              50.5 %                |              33.7 %                |
  152.    +------------------------------------+------------------------------------+
  153.  
  154.  
  155.  BenchMark 2:  Library opening tests:
  156.  ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  157.  
  158.   Test code:
  159.   ¯¯¯¯¯¯¯¯¯¯
  160.    /*  Code used to measure the time needed to open the reqtools.library
  161.    **  WITHOUT the ressourcetracking.library.  It means 409600 library
  162.    **  opens and closes.  Note: the library is loaded before the tests is
  163.    **  started. */
  164.  
  165.    int i, j;
  166.    APTR lib[4096];
  167.  
  168.       for (i=0;i<100;i++) {            /* do 100 times: */
  169.          for (j=0;j<4096;j++)            /* open reqtools 4096 times */
  170.             lib[j]=OpenLibrary("reqtools.library", 37);
  171.          for (j=4095;j>=0;j--)
  172.             if (lib[j])                  /* do 4096 pointer tests and */
  173.                CloseLibrary(lib[j]);     /* 4096 library closes */
  174.       }
  175.  
  176.    /*  Code used to measure the time needed to open the reqtools.library WITH
  177.    **  the ressourcetracking.library.  It means 409600 library opens and
  178.    **  closes.  Note: the library is loaded before the tests is started. */
  179.  
  180.    int i, j;
  181.    APTR mem[4096];
  182.  
  183.    for (i=0;i<100;i++) {               /* do 100 times: */
  184.       for (j=0;j<4096;j++)               /* open reqtools 4096 times */
  185.          lib[j]=rt_OpenLibrary("reqtools.library", 37);
  186.       rt_UnsetMarker();                  /* 4096 library closes */
  187.    }
  188.  
  189.  
  190.   Results:
  191.   ¯¯¯¯¯¯¯¯
  192.    +-------------------------------------------------------------------------+
  193.    |                             MEASURED TIMES                              |
  194.    +-------------------------------------------------------------------------+
  195.    |           WITH library            |           WITHOUT library           |
  196.    +-----------------------------------+-------------------------------------+
  197.    |            00:00:56.24            |             00:00:44.53             |
  198.    +-----------------------------------+-------------------------------------+
  199.  
  200.    +-------------------------------------------------------------------------+
  201.    |                            LIBRARY OVERHEAD                             |
  202.    +-------------------------------------------------------------------------+
  203.    |                                 26.3 %                                  |
  204.    +-------------------------------------------------------------------------+
  205.  
  206.  
  207. ============================= Archive contents =============================
  208.  
  209. Original  Packed Ratio    Date     Time    Name
  210. -------- ------- ----- --------- --------  -------------
  211.    13213    3208 75.7% 30-Aug-98 19:07:24 +Autodocs
  212.     8302    2335 71.8% 30-Aug-98 19:02:20 +RsrcTrackLib.readme
  213.     4765    1480 68.9% 30-Aug-98 19:02:20 +compiler.h
  214.      582     334 42.6% 30-Aug-98 19:02:20 +createlib.b
  215.      511     285 44.2% 30-Aug-98 19:02:22 +ressourcetracking.fd
  216.     1255     527 58.0% 30-Aug-98 19:02:22 +ressourcetracking_protos.h
  217.     1100     298 72.9% 30-Aug-98 19:02:22 +ressourcetracking_pragmas.h
  218.      511     272 46.7% 30-Aug-98 19:02:22 +ressourcetracking.h
  219.     2100     821 60.9% 30-Aug-98 19:02:22 +ressourcetracking.h
  220.     2117     830 60.7% 30-Aug-98 19:02:22 +ressourcetrackingbase.h
  221.     6062    2050 66.1% 30-Aug-98 19:02:20 +LibInit.c
  222.      722     416 42.3% 30-Aug-98 19:02:20 +make.b
  223.     1654     576 65.1% 30-Aug-98 19:02:20 +makefile
  224.      323     198 38.6% 30-Aug-98 19:02:22 +Oberon-A.readme
  225.     2518     947 62.3% 30-Aug-98 19:02:22 +ressourcetracking.mod
  226.      808     411 49.1% 30-Aug-98 19:02:22 +Test.mod
  227.     3692    2039 44.7% 30-Aug-98 19:02:22 +ressourcetracking.library
  228.    15716    4259 72.9% 30-Aug-98 19:02:20 +SampleFuncs.c
  229.     1714     566 66.9% 30-Aug-98 19:02:22 +SampleFuncs.h
  230.    10737    2563 76.1% 30-Aug-98 19:02:22 +StartUp.c
  231.     6576    3935 40.1% 30-Aug-98 19:02:22 +Test
  232.      944     393 58.3% 30-Aug-98 19:02:22 +Test.c
  233. -------- ------- ----- --------- --------
  234.    85922   28743 66.5% 10-Sep-98 11:05:48   22 files
  235.